Skip to content

Conversation

@theletterf
Copy link
Contributor

Alternative to #3735 where we keep syntax docs in docs-builder and use crosslinks instead.

leemthompo and others added 22 commits October 30, 2025 14:19
Copy syntax guide documentation from docs-builder repository to
contribute-docs/syntax/. Includes 37 markdown files covering MyST
syntax, directives, and custom Elastic documentation features.

Changes from original:
- Add legacy documentation section linking to AsciiDoc guide
- Fix reference from "See" to "refer to"
Copy contribution documentation from docs-builder to contribute-docs/contribute/.
Includes guides for local and web-based contribution, how-to guides for moving
files and redirects, and comprehensive cumulative documentation guidance.

Changes from original:
- Update absolute paths to relative paths for new location
- Add link to documentation tools in locally.md prerequisites
- Simplify on-the-web.md and add detailed GitHub editing steps
- Add legacy docs reference in on-the-web.md
- Fix cumulative docs link path in locally.md
- Update "See" to "refer to" throughout
- Remove branching strategy references (not migrated)
- Remove development section reference (not migrated)
- Update navigation title for contribute index
- Clean up local preview section wording
Create new tools.md page documenting helpful authoring tools including
the Elastic Docs VS Code extension. Includes animated demo and installation
instructions.

Features:
- VS Code extension description with key capabilities
- Availability in desktop and web editors (Codespaces, github.dev)
- Links to VS Code Marketplace and GitHub
- Screenshot showing extension in action
Create dedicated page for contributing to elastic.co/guide (legacy AsciiDoc
documentation). Consolidates legacy docs contribution information from
contribute index and on-the-web pages.

Includes:
- Overview of legacy documentation system and covered versions
- Web-based contribution workflow
- Local contribution guidance
- Cross-system update workflow using pandoc
Create index page for how-to section organizing practical guides for
common documentation tasks including moving files, setting up redirects,
and writing cumulative documentation.
Update main landing page to link to newly migrated content:
- Link to local syntax guide instead of external docs-builder
- Link to local contribution guide instead of external docs-builder
- Link to local legacy docs guide instead of external docs-builder

Provides clear entry points for all documentation systems.
Add syntax guide and contribution guides sections to toc.yml.
Organizes migrated content into logical hierarchy:

- Syntax guide with 37 markdown files
- Contribution guides organized by workflow (local, web, legacy)
- Documentation tools page
- How-to guides subsection with cumulative docs, file moves, and redirects
Change tools.mdd# to tools.md#vs-code-extension
- Copy shared _snippets folder from docs-builder
- Fix absolute paths (/syntax/, /contribute/) to relative paths
- Fix snippet includes to use correct relative paths
- Remove broken link to configure/content-set, link to external docs-builder instead
- Update configure/site reference to external docs-builder guide

These changes resolve path errors from moving content into contribute-docs.
- Use absolute paths (/contribute-docs/) for all cross-references
- Fix malformed relative paths (../syntax../, ../../.., etc)
- Escape substitution variables in example table with backticks

All 24 errors now resolved.
- Fix snippet includes in csv-include.md and reference.md to use absolute paths
- Fix malformed ../../../contribute-docs path to /contribute-docs
- Fix snippet reference to cumulative docs from syntax folder

Attempt to resolve remaining path errors.
Adds the tag-processing.md snippet file that was missing from the _snippets
folder. This file is referenced in cumulative-docs/index.md and is needed
for proper documentation rendering.
Updates syntax documentation to match latest docs-builder:
- Adds applies-to-admonitions.md snippet for admonitions with applies_to
- Adds applies-to-dropdowns.md snippet for dropdowns with applies_to badges
- Refactors admonitions.md and dropdowns.md to use new snippet includes

These changes align with upstream docs-builder updates made on Nov 3, 2025.
Removes the redundant /contribute-docs/contribute/ nesting by moving all
contribution guide files up one level to /contribute-docs/. This simplifies
URLs and makes the structure more intuitive.

Changes:
- Renamed contribute/index.md to contribute-index.md
- Moved all contribute/* files to contribute-docs/ root
- Moved contribute/how-to/ to contribute-docs/how-to/
- Moved contribute/_snippets/ to _snippets-contribute/
- Moved contribute/images/ to contribute-docs/images/
- Updated toc.yml to reflect flattened structure
- Updated all internal links throughout documentation

URLs before:
- /contribute-docs/contribute/locally
- /contribute-docs/contribute/how-to/move

URLs after:
- /contribute-docs/locally
- /contribute-docs/how-to/move
@theletterf theletterf closed this Nov 3, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants